home *** CD-ROM | disk | FTP | other *** search
/ Amiga Tools 2 / Amiga Tools 2.iso / musik / dtl / dtl0-format.txt < prev    next >
Text File  |  1995-03-09  |  8KB  |  161 lines
  1.          Description of the DES-Tracker v1.0 file format ("DTL0")
  2.          ========================================================
  3.  
  4.                              As of Dec 18, 1993
  5.  
  6.                          Written by Darren Schebek
  7.                      Copyright ©1993 by Darren Schebek
  8.                             All rights reserved
  9.  
  10.  
  11.  
  12.     This text file contains a description of the DES-Tracker v1.0 song module
  13. file format, henceforth referred to as the "DTL0" format.
  14.  
  15.     For those familiar with various module file formats, the "DTL0" file
  16. format is most closely related to the Soundtracker v2.6 file format.  As such,
  17. this is not an IFF format.  Rather, it's just another file format thrown on
  18. the heap.  However, it's more efficient and flexible than the Soundtracker
  19. v2.6 format (which is already *way* more efficient than the Noisetracker/
  20. Protracker file format), resulting in smaller module files.
  21.  
  22.     There are a few features worth noting about the "DTL0" file format.
  23. First, like with Soundtracker, patterns are 256 bytes long.  A "pattern" in
  24. this context is an array of 64 longword note events to be played by a single
  25. audio channel.  The "DTL0" format can handle up to 65,535 patterns in a single
  26. song file.  Soundtracker v2.6 can only handle up to 255.
  27.  
  28.     As a result of the above feature, the pattern sequence table requires
  29. 4-word elements (instead of 4-byte, like Soundtracker v2.6) in order to
  30. specify pattern numbers greater than 255.  The "DTL0" file format is smart, in
  31. that it will store 4-byte elements in the pattern sequence array if the number
  32. of unique patterns is less than or equal to 256.  If the number of unique
  33. patterns is greater than 256, then 4-word elements are stored.
  34.  
  35.     Also, the pattern sequence array has only as many elements as there are
  36. positions in the song.  If a song has 18 positions, then the array will be 18
  37. elements long in the file.  Soundtracker v2.6 always contains an array of 128
  38. 4-byte elements regardless of how many elements are actually used.
  39.  
  40.     Lastly, extra fields have been added to indicate intial timing conditions
  41. for the song.  One or two of these fields are rather specific to DES-Tracker,
  42. but they may still be of use to others nonetheless.
  43.  
  44.     Here is a byte-by-byte description of the file:
  45.  
  46.  
  47.  File      Field
  48. Offset      Size        Description
  49.   0           4         Four-byte ID code: "DTL0" indicating that this is
  50.                         a "DTL0" file format.
  51.  
  52.   4          20         The title of the song, padded with NULL's.
  53.  
  54.  24         930         Instrument info blocks.  There are 31 of them, and
  55.                         each one is 30 bytes in length.  An instrument info
  56.                         block looks like this:
  57.  
  58.                             22 bytes    Instrument's name.
  59.                              2 bytes    Length of instrument sample in words.
  60.                              1 byte     Its fine tune value (-8..+7).
  61.                              1 byte     Its default volume (0..64).
  62.                              2 bytes    Its repeat offset in words.
  63.                              2 bytes    Its repeat loop length in words.
  64.  
  65.                         An instrument info block with a length field that
  66.                         contains 0 is to be considered an "empty slot"
  67.                         (i.e., No instrument sample is associated with this
  68.                         instrument info block).
  69.  
  70. 954           1         Playback flags.  There are currently two of them:
  71.  
  72.                             Bit 0: Timing mode for playback. 0 = 60Hz playback.
  73.                                                              1 = 50Hz playback.
  74.  
  75.                             Bit 1: Tempo interpretation. If this bit is 0,
  76.                                    then SETTEMPO (command $F) operands are to
  77.                                    be considered as such:
  78.  
  79.                                         0..31  = Normal tempo operands.
  80.                                        32..255 = BPM tempo operands.
  81.  
  82.                                    If this bit is set to 1, then the
  83.                                    entire range (1..255) of the SETTEMPO
  84.                                    operand field is to be considered a
  85.                                    normal tempo operand (i.e., No BPM
  86.                                    tempos).
  87.  
  88. 955           1         Default (initial) tempo for playback (0..255).
  89.  
  90. 956           1         Fine tempo for playback.  This is a value in the
  91.                         range -128..127.  It represents a fine adjustment
  92.                         to the overall tempo of the song in units of
  93.                         0.078125Hz.  So, a value of 127 increases the
  94.                         overall tempo of the song by +10Hz, whereas a value
  95.                         of -128 decreases the overall tempo by -10Hz.
  96.  
  97. 957           1         Default number of iterations (0..255).  A value of
  98.                         0 here means that the song is meant to loop
  99.                         forever.  1 means play the song once and then stop,
  100.                         2 means play it twice, etc.
  101.  
  102. 958           2         The number of positions in the song (referenced in
  103.                         this document as nPos).  This is a value that should
  104.                         never be higher than 128.  It is a word for the sake
  105.                         of future consideration.  If this file format HAS a
  106.                         future, I should say. :)
  107.  
  108. 960           2         The number of unique patterns in the song
  109.                         (referenced here with nPatt).  Patterns are 256
  110.                         bytes long, containing 64 longword note events for a
  111.                         single audio channel.
  112.  
  113. 962     nPos * ( (nPatt > 256) ? 4 : 8)
  114.                         The pattern sequence array.  Each element in the
  115.                         array contains four pattern numbers - one for each
  116.                         audio channel that are to be played simultaneously.
  117.                         If the number of patterns is 256 or less then the
  118.                         pattern numbers will be byte values (4-byte array
  119.                         elements).  If the number of patterns is greater
  120.                         than 256 then the pattern numbers will be word values
  121.                         (4-word array elements).
  122.  
  123. Varies    nPatt * 256   The pattern data. There are nPatt patterns here.
  124.                         Each one is 256 bytes in length.  Protracker
  125.                         effects and "E" commands are allowed.
  126.  
  127. Varies     Varies       The instrument sample data appears here, immediately
  128.                         after the last pattern.  Sample data appears in the
  129.                         same order as the corresponding instrument info
  130.                         block (described previously).  There is no sample
  131.                         data for "empty slots" (i.e., instrument info blocks
  132.                         with a length field containing 0).
  133.  
  134. EOF
  135.  
  136.  
  137.     That's about all there is to it.  I would probably not have designed the
  138. "DTL0" file format had I not actually come across a song module that had over
  139. 256 unique patterns when converted from Protracker to Soundtracker v2.6.  This
  140. made me realize that such a thing is possible, and as I detest the
  141. inefficiency of the Noisetracker/Protracker file format, I felt I should come
  142. up with a variation of Soundtracker v2.6 that could handle more unique
  143. patterns.  Nobody is obligated to use this format and in all truth, perhaps
  144. nobody really should use it.  However, it's perfectly safe to use, as
  145. DES-Tracker can easily convert back and forth between DTL0 and NoiseTracker/
  146. Protracker.
  147.  
  148.     Note that I decided to retain the storage of "empty" instrument info
  149. blocks to preserve instrument names that have been stomped for the sake of
  150. a silly message.  This is normally a practice I abhor since it's only going
  151. to cause problems in the long run.  Really, SampleTexts are a much, much
  152. better idea and you can say a lot more with them.  They're a far better
  153. alternative to stomping instrument names.  If you want to stomp instrument
  154. names, give them names like "Inst1", "Inst2", etc, or something.  Although
  155. there's absolutely no point in eradicating instrument names in the first
  156. place.
  157.  
  158.                                             - Darren Schebek
  159.                                               dschebek@outb.wimsey.bc.ca
  160.  
  161.